home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 January: Mac OS SDK / Dev.CD Jan 99 SDK2.toast / Development Kits / QuickTake Digital Camera / MyQuickTakeApp 1.0.1TC7 ƒ / Headers / Preferences (develop 18) / StdPrefsLib.h < prev    next >
Encoding:
Text File  |  1994-11-24  |  11.9 KB  |  298 lines  |  [TEXT/KAHL]
  1. /*
  2.     File:        StdPrefsLib.h
  3.  
  4.     Contains:    Header file for standard preferences library routines.
  5.  
  6.                 Refer to develop Issue 18, "The Right Way to Implement 
  7.                 Preferences Files", for additional details on this code.
  8.                 
  9.     Written by:    Gary Woodcock
  10.  
  11.     Copyright:    © 1993-94 by Apple Computer, Inc.
  12.     Change History (most recent first):
  13.     
  14.                   3/3/94    Version 1.0.
  15.     
  16.     Notes:         This code uses Apple's Universal Interfaces for C.
  17.     
  18.                 Send bug reports to Gary Woodcock at AOL: gwoodcock
  19.                 or Internet: gwoodcock@aol.com.
  20. */
  21.  
  22. //-----------------------------------------------------------------------
  23. // Includes
  24.  
  25. #ifndef    _STDPREFSLIB_
  26. #define    _STDPREFSLIB_
  27.  
  28. #include "CompileFlags.h"
  29.  
  30. #ifndef forRez
  31.  
  32. #endif forRez
  33.  
  34. //-----------------------------------------------------------------------
  35. // Public constants
  36.  
  37. #ifndef forRez
  38.  
  39. // Valid version resource ('vers') ID's
  40. enum
  41. {
  42.     kVers1 = 1,
  43.     kVers2
  44. };
  45.  
  46. //-----------------------------------------------------------------------
  47. // Public interfaces
  48.  
  49. #ifdef __cplusplus
  50. extern "C" {
  51. #endif __cplusplus
  52.  
  53. //-----------------------------------------------------------------------
  54. // NewPreferencesFile creates a new preferences file with the specified
  55. // creator, file type and name in the System Folder (prior to System 7)
  56. // or the Preferences folder (System 7 or later). File names with zero-length
  57. // strings are not permitted. You can optionally specify a custom 
  58. // preferences folder of your own with the folderName argument; pass nil
  59. // for this argument if you don't want to use a custom preferences
  60. // folder. If a folder name that is not a zero-length string is provided, 
  61. // NewPreferencesFile checks to see if the folder exists; if it doesn't, 
  62. // NewPreferencesFile creates the folder. Another option is to provide
  63. // the name of the program (application, extension, etc.) in the ownerName
  64. // argument; if this argument is supplied, a custom application-missing
  65. // message string resource is created for the preferences file.
  66. //
  67. // Errors:
  68. //
  69. //      paramErr    - The fileName or ownerName argument is a zero-length 
  70. //                    string.
  71. //      dupFNErr    - A preferences file with this name, creator and file
  72. //                  type already exists.
  73. //
  74. //      Other ResError() or file system codes can be returned, but 
  75. //      this should not normally occur.
  76. //-----------------------------------------------------------------------
  77. pascal OSErr
  78. NewPreferencesFile (OSType creator, OSType fileType, 
  79.     ConstStr31Param fileName, ConstStr31Param folderName, 
  80.     ConstStr31Param ownerName);
  81.     
  82. //-----------------------------------------------------------------------
  83. // OpenPreferencesFile opens the preferences file with the specified
  84. // creator and file type.  You must have created the file with the 
  85. // NewPreferencesFile call before making this call. 
  86. //
  87. // Errors:
  88. //
  89. //      paramErr    - The fRefNum argument is nil.
  90. //    fnfErr      - There is no preferences file with the specified
  91. //                  creator and file type; use NewPreferencesFile to 
  92. //                    create one.
  93. //
  94. //      Other ResError() or file system codes can be returned, but 
  95. //      this should not normally occur.
  96. //-----------------------------------------------------------------------
  97. pascal OSErr
  98. OpenPreferencesFile (OSType creator, OSType fileType, short *fRefNum);
  99.     
  100. //-----------------------------------------------------------------------
  101. // ClosePreferencesFile closes the currently open preferences file
  102. // for this instance of the standard preferences component.  If there is
  103. // no preferences file currently open, an error is returned.
  104. //
  105. // Errors:
  106. //
  107. //      paramErr    - Bad file reference in fRefNum argument.
  108. //
  109. //      Other ResError() codes can be returned, but this should not 
  110. //    normally occur.
  111. //-----------------------------------------------------------------------
  112. pascal OSErr
  113. ClosePreferencesFile (short fRefNum);
  114.     
  115. //-----------------------------------------------------------------------
  116. // DeletePreferencesFile deletes the preferences file with the specified
  117. // creator and file type.  If the preferences file is open, an error is 
  118. // returned; you must make sure any preferences files are closed before 
  119. // attempting to delete them. 
  120. //
  121. // Errors:
  122. //
  123. //      fBsyErr     - The specified preferences file is currently open, 
  124. //                    and must be closed before it can be deleted.
  125. //      fnfErr      - A preferences file with the specified creator and
  126. //                    file type could not be found.
  127. //
  128. //      Other file system codes can be returned, but this should not 
  129. //    normally occur.
  130. //-----------------------------------------------------------------------
  131. pascal OSErr
  132. DeletePreferencesFile (OSType creator, OSType fileType);
  133.  
  134. //-----------------------------------------------------------------------
  135. // DeletePreferencesFolder deletes the preferences folder specified by the
  136. // folderName argument. An attempt will be made to locate the specified
  137. // folder by first searching the Preferences folder and its nested folders
  138. // (if the Preferences folder exists), then by searching the System Folder.
  139. //
  140. // Errors:
  141. //
  142. //    paramErr    - The folderName argument is a zero-length string.
  143. //      dirNFErr      - A folder with the specified name could not be
  144. //                    found.
  145. //
  146. //      Other file system codes can be returned, but this should not 
  147. //    normally occur.
  148. //-----------------------------------------------------------------------
  149. pascal OSErr
  150. DeletePreferencesFolder (ConstStr31Param folderName);
  151.     
  152. //-----------------------------------------------------------------------
  153. // PreferencesFileExists determines whether a preferences file already
  154. // exists or not. If the file specified by the creator and file type 
  155. // exists in either the Preferences folder (anywhere) or in the System 
  156. // Folder, true is returned; if it doesn't exist, false is returned.
  157. //
  158. // Errors:
  159. //
  160. //      None.
  161. //-----------------------------------------------------------------------
  162. pascal Boolean
  163. PreferencesFileExists (OSType creator, OSType fileType);
  164.     
  165. //-----------------------------------------------------------------------
  166. // GetPreferencesFileVersion returns the contents of the specified 'vers'
  167. // resource of the currently open preferences file.  You can use this 
  168. // information to distinguish between current and older versions of your 
  169. // preferences files (say, between the preferences files for version 1.5 
  170. // and 1.0 of your application program).  You must have called 
  171. // OpenPreferencesFile previously before making this call.  Only versID's 
  172. // with a value of kVers1 or kVers2 are allowed.
  173. //
  174. // Errors:
  175. //
  176. //      paramErr    - A value other than kVers1 or kVers2 was passed for the 
  177. //                    versID argument, a bad address was passed for the 
  178. //                    numVersion argument or the regionCode argument, or the
  179. //                    fRefNum argument contains a bad file reference.
  180. //        
  181. //      Other file system, ResError(), or MemError() codes can be returned,
  182. //    but this should not normally occur.
  183. //-----------------------------------------------------------------------
  184. pascal OSErr
  185. GetPreferencesFileVersion (short fRefNum, short versID, 
  186.     NumVersion *numVersion, short *regionCode, 
  187.     ConstStr255Param shortVersionStr, ConstStr255Param longVersionStr);
  188.     
  189. //-----------------------------------------------------------------------
  190. // SetPreferencesFileVersion lets you set the contents of the specified 
  191. // 'vers' resource of the currently open preferences file.  You must have 
  192. // called OpenPreferencesFile previously before making this call.  Only 
  193. // versID's with a value of kVers1 or kVers2 are allowed.
  194. //
  195. // Errors:
  196. //
  197. //      paramErr    - A value other than kVers1 or kVers2 was passed for 
  198. //                    the versID argument, a bad address was passed for 
  199. //                    the numVersion argument, or the fRefNum argument
  200. //                    contains a bad file reference.
  201. //
  202. //      Other file system, ResError(), or MemError() codes can be returned,
  203. //    but this should not normally occur.
  204. //-----------------------------------------------------------------------
  205. pascal OSErr
  206. SetPreferencesFileVersion (short fRefNum, short versID, 
  207.     NumVersion *numVersion, short regionCode, 
  208.     ConstStr255Param shortVersionStr, ConstStr255Param longVersionStr);
  209.      
  210. //-----------------------------------------------------------------------
  211. // ReadPreference reads the specified preference resource from the 
  212. // currently open preferences file.  If you pass in nil for the address 
  213. // of the resourceID argument, or if you pass in 0 for the value of the 
  214. // resource ID, then ReadPreferences will find the first resource with 
  215. // the specified type in the currently open preferences file.  If you pass 
  216. // in 0 for the value of the resource ID, then OpenPreferencesFile will 
  217. // return the resourceID corresponding to the preference resource it found.  
  218. // You must have called OpenPreferencesFile previously before making this 
  219. // call.
  220. //
  221. // Errors:
  222. //
  223. //      paramErr    - The address of the preference argument is nil, or 
  224. //                    the fRefNum argument contains a bad file reference.
  225. //      resNotFound - No resource with the specified type and/or ID was
  226. //                  found.
  227. //
  228. //    Other ResError() codes can be returned, but this should not 
  229. //    normally occur.
  230. //-----------------------------------------------------------------------
  231. pascal OSErr
  232. ReadPreference (short fRefNum, ResType resourceType, short *resourceID, 
  233.     Handle *preference);
  234.     
  235. //-----------------------------------------------------------------------
  236. // WritePreference writes the specified preference resource to the 
  237. // currently open preferences file.  If you pass in nil for the address 
  238. // of the resourceID argument, or if you pass in 0 for the value of the 
  239. // resource ID, then WritePreferences assigns the preference resource a 
  240. // resource ID and returns it in the resourceID argument (if its address 
  241. // isn't nil).  If a resource with the same type and ID already exists 
  242. // in the preferences file, the existing resource is replaced with the 
  243. // new one.  You must have called OpenPreferencesFile previously before 
  244. // making this call.  WritePreference checks to make sure that there is a 
  245. // minimum amount of disk space left before actually writing out the 
  246. // preference to the preferences file - if there isn't enough disk space, 
  247. // the preferences file will be untouched, and an error will be returned.
  248. // The actual size of this minimum amount is dependent on the allocation
  249. // block size of the volume that the preferences file is located on.  
  250. // IMPORTANT NOTE:  It is the caller's responsibility to dispose the 
  251. // memory occupied by the preference argument - WritePreference does NOT 
  252. // dispose this memory.
  253. //
  254. // Errors:
  255. //
  256. //      paramErr       - The preference argument is nil, or the fRefNum argument
  257. //                    contains a bad file reference.
  258. //    dskFulErr   - The preference can't be written and still maintain a 
  259. //                  minimum amount of free space on the disk.
  260. //
  261. //      Other MemError() or ResError() codes can be returned, but this should
  262. //    not normally occur.
  263. //-----------------------------------------------------------------------
  264. pascal OSErr
  265. WritePreference (short fRefNum, ResType resourceType, short *resourceID, 
  266.     Handle preference);
  267.     
  268. //-----------------------------------------------------------------------
  269. // DeletePreference deletes the specified preference resource from the 
  270. // currently open preferences file.  If you pass in 0 for the resourceID 
  271. // argument, then DeletePreference will delete the first resource of the 
  272. // specified type in the currently open preferences file.  You must have 
  273. // called OpenPreferenceFile previously before making this call.
  274. //
  275. // Errors:
  276. //
  277. //      paramErr    - The fRefNum argument contains a bad file reference.
  278. //      resNotFound - No resource with the specified type and/or ID was
  279. //                  found.
  280. //
  281. //      Other MemError() or ResError() codes can be returned, but this 
  282. //    should not normally occur.
  283. //-----------------------------------------------------------------------
  284. pascal OSErr
  285. DeletePreference (short fRefNum, ResType resourceType, short resourceID);
  286.     
  287. #ifdef __cplusplus
  288. }
  289. #endif __cplusplus
  290.  
  291. #endif forRez
  292.  
  293. //-----------------------------------------------------------------------
  294.  
  295. #endif _STDPREFSLIB_
  296.  
  297. //-----------------------------------------------------------------------
  298.